improve code documentation and remove dead code #2485
Conversation
rdmark
changed the title
rdmark
force-pushed
the
2472-code-documentation-that-isnt-doxygen-compliant
branch
9 times, most recently
from
07a8f7d to
2ec04fa
Compare
Touch up all code documentation structure warnings thrown by doxygen, while correcting typos and grammar Remove parameters and entire functions that are unused, rather than fixing the code documentation
Now since the code documentation is clean and compliant, let's treat warnings as errors in doxygen However, do this only when enabling -Dwith-doxygen-strict=true
rdmark
force-pushed
the
2472-code-documentation-that-isnt-doxygen-compliant
branch
2 times, most recently
from
c1298fb to
578346d
Compare
The vfs module uses macros to manage function parameters, which doxygen does not handle gracefully, so defining those outright in the Doxyfile As part of this change, removing the _U_ unused attribute wrapper macros from the definitions themselves since they interfere with the expansion We now also preprocess away macros and keywords irrelevant to documentation
Touches up a few code documentation comments that were revealed in the process
rdmark
force-pushed
the
2472-code-documentation-that-isnt-doxygen-compliant
branch
from
47522ab to
fb334bd
Compare
|
|
This was a deeper rabbit hole than I anticipated. When I started digging, there where all sorts of code documentation in unusual formats, and corner cases that required additional doxygen configuration or refactoring of surrounding code. I'm pretty happy with how it has turned out now. The latest branch revision has been published to the website again: https://netatalk.io/developer/ The one ugly workaround right now is some hard coded preprocessor mapping of the function parameter macros that the libatalk/vfs module uses. See |
rdmark
deleted the
2472-code-documentation-that-isnt-doxygen-compliant
branch
Touch up all code documentation syntax warnings thrown by doxygen, standardizing on Qt style with consistent application of command tags, while correcting typos and grammar
Remove parameters and entire functions that are unused, rather than fixing the code documentation for dead code
Now since the code documentation is clean and compliant, let's treat warnings as errors in doxygen
Introducing new meson option
-Dwith-doxygen-strict=truewhich enables error-on-warning behavior in doxygen; the reason for making this opt-in, is because doxygen will treat any unknown Doxyfile option as a warning=>error, so if you use anything but the very latest doxygen 1.14 you get a ton of errors (because doxygen apparently keeps adding new options all the time)Finally, build doxygen docs in a new job in the Tests workflow so that we can get an early warning when invalid code documentation gets introduced